Construction function

1. check key validity
2. create report
3. check if file exist
4. open file
5. check if it's a valid SGX SDK PF (by size)

https://github.com/intel/linux-sgx/blob/master/sdk/protected_fs/sgx_tprotected_fs/file_init.cpp

protected_fs_file::protected_fs_file(const char* filename, const char* mode, const sgx_aes_gcm_128bit_key_t* import_key, const sgx_aes_gcm_128bit_key_t* kdk_key)
{
    sgx_status_t status = SGX_SUCCESS;
    uint8_t result = 0;
    int32_t result32 = 0;
    
    init_fields();

    if (filename == NULL || mode == NULL || 
        strnlen(filename, 1) == 0 || strnlen(mode, 1) == 0)
    {
        last_error = EINVAL;
        return;
    }

    if (strnlen(filename, FULLNAME_MAX_LEN) >= FULLNAME_MAX_LEN - 1)
    {
        last_error = ENAMETOOLONG;
        return;
    }

    if (import_key != NULL && kdk_key != NULL)
    {// import key is used only with auto generated keys
        last_error = EINVAL;
        return;
    }

    status = sgx_create_report(NULL, NULL, &report);
    if (status != SGX_SUCCESS)
    {
        last_error = status;
        return;
    }

    result32 = sgx_thread_mutex_init(&mutex, NULL);
    if (result32 != 0)
    {
        last_error = result32;
        return;
    }

    if (init_session_master_key() == false) 
        // last_error already set
        return;

    if (kdk_key != NULL)
    {
        // for new file, this value will later be saved in the meta data plain part (init_new_file)
        // for existing file, we will later compare this value with the value from the file (init_existing_file)
        use_user_kdk_key = 1; 
        memcpy(user_kdk_key, kdk_key, sizeof(sgx_aes_gcm_128bit_key_t));
    }
    
    // get the clean file name (original name might be clean or with relative path or with absolute path...)
    char clean_filename[FILENAME_MAX_LEN];
    if (cleanup_filename(filename, clean_filename) == false)
        // last_error already set
        return;
    
    if (import_key != NULL)
    {// verify the key is not empty - note from SAFE review
        sgx_aes_gcm_128bit_key_t empty_aes_key = {0};
        if (consttime_memequal(import_key, &empty_aes_key, sizeof(sgx_aes_gcm_128bit_key_t)) == 1)
        {
            last_error = EINVAL;
            return;
        }
    }

    if (parse_mode(mode) == false)
    {
        last_error = EINVAL;
        return;
    }

    status = u_sgxprotectedfs_check_if_file_exists(&result, filename); // if result == 1 --> file exists
    if (status != SGX_SUCCESS)
    {
        last_error = status;
        return;
    }

    if (open_mode.write == 1 && result == 1)
    {// try to delete existing file
        int32_t saved_errno = 0;

        result32 = remove(filename);
        if (result32 != 0)
        {
            // either can't delete or the file was already deleted by someone else
            saved_errno = errno;
            errno = 0;
        }

        // re-check
        status = u_sgxprotectedfs_check_if_file_exists(&result, filename);
        if (status != SGX_SUCCESS || result == 1)
        {
            last_error = (status != SGX_SUCCESS) ? status :
                         (saved_errno != 0) ? saved_errno : EACCES;
            return;
        }
    }

    if (open_mode.read == 1 && result == 0)
    {// file must exists
        last_error = ENOENT;
        return;
    }

    if (import_key != NULL && result == 0)
    {// file must exists - otherwise the user key is not used
        last_error = ENOENT;
        return;
    }

    // now open the file
    read_only = (open_mode.read == 1 && open_mode.update == 0); // read only files can be opened simultaneously by many enclaves

    do {
        status = u_sgxprotectedfs_exclusive_file_open(&file, filename, read_only, &real_file_size, &result32);
        if (status != SGX_SUCCESS || file == NULL)
        {
            last_error = (status != SGX_SUCCESS) ? status :
                         (result32 != 0) ? result32 : EACCES;
            break;
        }

        if (real_file_size < 0)
        {
            last_error = EINVAL;
            break;
        }

        if (real_file_size % NODE_SIZE != 0)
        {
            last_error = SGX_ERROR_FILE_NOT_SGX_FILE;
            break;
        }
        
        strncpy(recovery_filename, filename, FULLNAME_MAX_LEN - 1); // copy full file name
        recovery_filename[FULLNAME_MAX_LEN - 1] = '\0'; // just to be safe
        size_t full_name_len = strnlen(recovery_filename, RECOVERY_FILE_MAX_LEN);
        strncpy(&recovery_filename[full_name_len], "_recovery", 10);

        if (real_file_size > 0)
        {// existing file
            if (open_mode.write == 1) // redundant check, just in case
            {
                last_error = EACCES;
                break;
            }

            if (init_existing_file(filename, clean_filename, import_key) == false)
                break;
                
            if (open_mode.append == 1 && open_mode.update == 0)
                offset = encrypted_part_plain.size;
        }
        else
        {// new file
            if (init_new_file(clean_filename) == false)
                break;
        }

        file_status = SGX_FILE_STATUS_OK;

    } while(0);

    if (file_status != SGX_FILE_STATUS_OK)
    {
        if (file != NULL)
        {
            u_sgxprotectedfs_fclose(&result32, file); // we don't care about the result
            file = NULL;
        }
    }
}

See also: C++ fwrite

size_t protected_fs_file::write(const void* ptr, size_t size, size_t count)
{
    if (ptr == NULL || size == 0 || count == 0)
        return 0;

    int32_t result32 = sgx_thread_mutex_lock(&mutex);
    if (result32 != 0)
    {
        last_error = result32;
        file_status = SGX_FILE_STATUS_MEMORY_CORRUPTED;
        return 0;
    }

    size_t data_left_to_write = size * count;

    // prevent overlap...
#if defined(_WIN64) || defined(__x86_64__)
    if (size > UINT32_MAX || count > UINT32_MAX)
    {
        last_error = EINVAL;
        sgx_thread_mutex_unlock(&mutex);
        return 0;
    }
#else
    if (((uint64_t)((uint64_t)size * (uint64_t)count)) != (uint64_t)data_left_to_write)
    {
        last_error = EINVAL;
        sgx_thread_mutex_unlock(&mutex);
        return 0;
    }
#endif

    if (sgx_is_outside_enclave(ptr, data_left_to_write))
    {
        last_error = SGX_ERROR_INVALID_PARAMETER;
        sgx_thread_mutex_unlock(&mutex);
        return 0;
    }

    if (file_status != SGX_FILE_STATUS_OK)
    {
        last_error = SGX_ERROR_FILE_BAD_STATUS;
        sgx_thread_mutex_unlock(&mutex);
        return 0;
    }

    if (open_mode.append == 0 && open_mode.update == 0 && open_mode.write == 0)
    {
        last_error = EACCES;
        sgx_thread_mutex_unlock(&mutex);
        return 0;
    }

    if (open_mode.append == 1)
        offset = encrypted_part_plain.size; // add at the end of the file

    const unsigned char* data_to_write = (const unsigned char*)ptr;

    // the first block of user data is written in the meta-data encrypted part
    if (offset < MD_USER_DATA_SIZE)
    {
        size_t empty_place_left_in_md = MD_USER_DATA_SIZE - (size_t)offset; // offset is smaller than MD_USER_DATA_SIZE
        if (data_left_to_write <= empty_place_left_in_md)
        {
            memcpy(&encrypted_part_plain.data[offset], data_to_write, data_left_to_write);
            offset += data_left_to_write;
            data_to_write += data_left_to_write; // not needed, to prevent future errors
            data_left_to_write = 0;
        }
        else
        {
            memcpy(&encrypted_part_plain.data[offset], data_to_write, empty_place_left_in_md);
            offset += empty_place_left_in_md;
            data_to_write += empty_place_left_in_md;
            data_left_to_write -= empty_place_left_in_md;
        }
        
        if (offset > encrypted_part_plain.size)
            encrypted_part_plain.size = offset; // file grew, update the new file size

        need_writing = true;
    }

    while (data_left_to_write > 0)
    {
        file_data_node_t* file_data_node = NULL;
        file_data_node = get_data_node(); // return the data node of the current offset, will read it from disk or create new one if needed (and also the mht node if needed)
        if (file_data_node == NULL)
            break;

        size_t offset_in_node = (size_t)((offset - MD_USER_DATA_SIZE) % NODE_SIZE);
        size_t empty_place_left_in_node = NODE_SIZE - offset_in_node;
        
        if (data_left_to_write <= empty_place_left_in_node)
        { // this will be the last write
            memcpy(&file_data_node->plain.data[offset_in_node], data_to_write, data_left_to_write);
            offset += data_left_to_write;
            data_to_write += data_left_to_write; // not needed, to prevent future errors
            data_left_to_write = 0;
        }
        else
        {
            memcpy(&file_data_node->plain.data[offset_in_node], data_to_write, empty_place_left_in_node);
            offset += empty_place_left_in_node;
            data_to_write += empty_place_left_in_node;
            data_left_to_write -= empty_place_left_in_node;

        }

        if (offset > encrypted_part_plain.size)
            encrypted_part_plain.size = offset; // file grew, update the new file size

        if (file_data_node->need_writing == false)
        {
            file_data_node->need_writing = true;
            file_mht_node_t* file_mht_node = file_data_node->parent;
            while (file_mht_node->mht_node_number != 0) // set all the mht parent nodes as 'need writing'
            {
                file_mht_node->need_writing = true;
                file_mht_node = file_mht_node->parent;
            }
            root_mht.need_writing = true;
            need_writing = true;
        }
    }

    sgx_thread_mutex_unlock(&mutex);

    size_t ret_count = ((size * count) - data_left_to_write) / size;
    return ret_count;
}

The inner implementations are in https://github.com/intel/linux-sgx/blob/master/sdk/protected_fs/sgx_tprotected_fs/sgx_tprotected_fs.cpp.

See also:

SDK_PF_New (protected_fs_file::protected_fs_file)

SDK_ProtectedFileClass

SGX_PF_Class

Internal APIs

Open

1. new protected_fs_file (SDK_PF_New)
2. if no error, return handle

static SGX_FILE* sgx_fopen_internal(const char* filename, const char* mode, const sgx_key_128bit_t *auto_key, const sgx_key_128bit_t *kdk_key)
{
    protected_fs_file* file = NULL;

    if (filename == NULL || mode == NULL)
    {
        errno = EINVAL;
        return NULL;
    }

    try {
        file = new protected_fs_file(filename, mode, auto_key, kdk_key);
    }
    catch (std::bad_alloc& e) {
        (void)e; // remove warning
        errno = ENOMEM;
        return NULL;
    }

    if (file->get_error() != SGX_FILE_STATUS_OK)
    {
        errno = file->get_error();
        delete file;
        file = NULL;
    }

    return (SGX_FILE*)file;
}

Write

size_t sgx_fwrite(const void* ptr, size_t size, size_t count, SGX_FILE* stream)
{
    if (ptr == NULL || stream == NULL || size == 0 || count == 0)
        return 0;

    protected_fs_file* file = (protected_fs_file*)stream;

    return file->write(ptr, size, count);
}

Write in PF Class

User level APIs are in https://github.com/intel/linux-sgx/blob/master/common/inc/sgx_tprotected_fs.h,

See also: Implementation

/* sgx_fopen
 *  Purpose: open existing protected file (created with previous call to sgc_fopen) or create a new one (see c++ fopen documentation for more details).
 *
 *  Parameters:
 *      filename - [IN] the name of the file to open/create.
 *      mode - [IN] open mode. only supports 'r' or 'w' or 'a' (one and only one of them must be present), and optionally 'b' and/or '+'.
 *      key - [IN] encryption key that will be used for the file encryption
 *      NOTE - the key is actually used as a KDK (key derivation key) and only for the meta-data node, and not used directly for the encryption of any part of the file
 *             this is important in order to prevent hitting the key wear-out problem, and some other issues with GCM encryptions using the same key
 *
 *  Return value:
 *     SGX_FILE*  - pointer to the newly created file handle, NULL if an error occurred - check errno for the error code.
*/
SGX_FILE* SGXAPI sgx_fopen(const char* filename, const char* mode, const sgx_key_128bit_t *key);

/* sgx_fwrite
 *  Purpose: write data to a file (see c++ fwrite documentation for more details).
 *
 *  Parameters:
 *      ptr - [IN] pointer to the input data buffer
 *      size - [IN] size of data block
 *      count - [IN] count of data blocks to write
 *      stream - [IN] the file handle (opened with sgx_fopen or sgx_fopen_auto_key)
 *
 *  Return value:
 *     size_t  - number of 'size' blocks written to the file, 0 in case of an error - check sgx_ferror for error code
*/
size_t SGXAPI sgx_fwrite(const void* ptr, size_t size, size_t count, SGX_FILE* stream);


/* sgx_fread
 *  Purpose: read data from a file (see c++ fread documentation for more details).
 *
 *  Parameters:
 *      ptr - [OUT] pointer to the output data buffer
 *      size - [IN] size of data block
 *      count - [IN] count of data blocks to write
 *      stream - [IN] the file handle (opened with sgx_fopen or sgx_fopen_auto_key)
 *
 *  Return value:
 *     size_t  - number of 'size' blocks read from the file, 0 in case of an error - check sgx_ferror for error code
*/
size_t SGXAPI sgx_fread(void* ptr, size_t size, size_t count, SGX_FILE* stream);

/* sgx_fflush
 *  Purpose: force actual write of all the cached data to the disk (see c++ fflush documentation for more details).
 *
 *  Parameters:
 *      stream - [IN] the file handle (opened with sgx_fopen or sgx_fopen_auto_key)
 *
 *  Return value:
 *     int32_t  - result, 0 on success, 1 in case of an error - check sgx_ferror for error code
*/
int32_t SGXAPI sgx_fflush(SGX_FILE* stream);

int32_t SGXAPI sgx_fclose(SGX_FILE* stream);
int64_t SGXAPI sgx_ftell(SGX_FILE* stream);
int32_t SGXAPI sgx_fseek(SGX_FILE* stream, int64_t offset, int origin);

...

https://github.com/intel/linux-sgx/blob/master/sdk/protected_fs/sgx_tprotected_fs/protected_fs_file.h

class protected_fs_file
{
private:
    union {
        struct {
            uint64_t meta_data_node_number; // for recovery purpose, so it is easy to write this node
            meta_data_node_t file_meta_data; // actual data from disk's meta data node
        };
        recovery_node_t meta_data_recovery_node;
    };

    meta_data_encrypted_t encrypted_part_plain; // encrypted part of meta data node, decrypted
    
    file_mht_node_t root_mht; // the root of the mht is always needed (for files bigger than 3KB)

    FILE* file; // OS's FILE pointer
    
    open_mode_t open_mode;
    uint8_t read_only;
    int64_t offset; // current file position (user's view)
    bool end_of_file; // flag

    int64_t real_file_size;
    
    bool need_writing; // flag
    uint32_t last_error; // last operation error
    protected_fs_status_e file_status;
    
    sgx_thread_mutex_t mutex;

    uint8_t use_user_kdk_key;
    sgx_aes_gcm_128bit_key_t user_kdk_key; // recieved from user, used instead of the seal key

    sgx_aes_gcm_128bit_key_t cur_key;
    sgx_aes_gcm_128bit_key_t session_master_key;
    uint32_t master_key_count;
    
    char recovery_filename[RECOVERY_FILE_MAX_LEN]; // might include full path to the file

    lru_cache cache;

    // these don't change after init...
    sgx_iv_t empty_iv;
    sgx_report_t report;

    void init_fields();
    bool cleanup_filename(const char* src, char* dest);
    bool parse_mode(const char* mode);
    bool file_recovery(const char* filename);
    bool init_existing_file(const char* filename, const char* clean_filename, const sgx_aes_gcm_128bit_key_t* import_key);
    bool init_new_file(const char* clean_filename);
    
    bool generate_secure_blob(sgx_aes_gcm_128bit_key_t* key, const char* label, uint64_t physical_node_number, sgx_aes_gcm_128bit_tag_t* output);
    bool generate_secure_blob_from_user_kdk(bool restore);
    bool init_session_master_key();
    bool derive_random_node_key(uint64_t physical_node_number);
    bool generate_random_meta_data_key();
    bool restore_current_meta_data_key(const sgx_aes_gcm_128bit_key_t* import_key);
    
    
    file_data_node_t* get_data_node();
    file_data_node_t* read_data_node();
    file_data_node_t* append_data_node();
    file_mht_node_t* get_mht_node();
    file_mht_node_t* read_mht_node(uint64_t mht_node_number);
    file_mht_node_t* append_mht_node(uint64_t mht_node_number);
    bool write_recovery_file();
    bool set_update_flag(bool flush_to_disk);
    void clear_update_flag();
    bool update_all_data_and_mht_nodes();
    bool update_meta_data_node();
    bool write_all_changes_to_disk(bool flush_to_disk);
    void erase_recovery_file();
    bool internal_flush(/*bool mc,*/ bool flush_to_disk);

public:
    protected_fs_file(const char* filename, const char* mode, const sgx_aes_gcm_128bit_key_t* import_key, const sgx_aes_gcm_128bit_key_t* kdk_key);
    ~protected_fs_file();

    size_t write(const void* ptr, size_t size, size_t count);
    size_t read(void* ptr, size_t size, size_t count);
    int64_t tell();
    int seek(int64_t new_offset, int origin);
    bool get_eof();
    uint32_t get_error();
    void clear_error();
    int32_t clear_cache();
    bool flush(/*bool mc*/);
    bool pre_close(sgx_key_128bit_t* key, bool import);
    static int32_t remove(const char* filename);
};